home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 1
/
Cream of the Crop 1.iso
/
PROGRAM
/
KSLIB11.ARJ
/
FUNCLIST.DOC
< prev
next >
Wrap
Text File
|
1991-11-13
|
81KB
|
2,788 lines
Function CFcolcvt
Prototype in cf.h
Module cf
Library tll
int CFcolcvt(char *s)
Converts a character string into it's corresponding colour number.
Parameters
s The string to convert.
Returns
The number of the color the string describes, or -1 if the string
could not be matched against one of the known colours.
-------------------------------------------------------------------------------
Function CFcolor
Prototype in cf.h
Module cf
Library tll
char *CFcolor(int c)
Returns the string corresponding to the specified colour number.
Parameters
c The number of the colour.
Returns
A pointer to the character string describing the colour, or NULL
if the colour is out of range.
-------------------------------------------------------------------------------
Function CFcolval
Prototype in cf.h
Module cf
Library tll
int CFcolval(char *s)
Converts a string of the form :
foreground,background
into the corresponding integer value for use when setting the screen
colour. Two locally declared static variables are used to hold the
colour once determined. These are initially set to white on black.
If either part of the string is missing, the corresponding part of the
colour is left unchanged. Thus, the following commands, if executed
consecutively from the start of a program, would change the screen
colours as follows :
Command Screen colour after executing
-------------------- -----------------------------
At start of program white on black
CFcolval("green,brown"); green on brown
CFcolval("blue"); blue on brown
CFcolval(",white"); blue on white
Parameters
s The string to convert
Returns
The integer corresponding to the new screen colours.
-------------------------------------------------------------------------------
Function CFconf
Prototype in cf.h
Module cf
Library tll
int CFconf(char *f,CFdata *d)
Read the specified config file into the specified variables. CFopen is
called to open the config file as normal, then CFread is repeatedly
called to read in the file. Each valid assignment statement is checked
against the list of items parsed, and if a match is found, that variable
is updated. Any invalid assignment statements are ignored.
Parameters :
f The name of the config file as per CFopen.
d Pointer to a list of valid assignment commands. Each item
contains a character string and a pointer to the variable to
hold that value. The character string holds the variable type
in the first character position, and the <cmd> in the rest.
Valid types are : S : String value (xxxxx)
C : Color value (foreground,background)
I : Integer value (nnn)
L : Long value (nnn)
F : Float value (nnn.nn)
D : Double value (nnn.nn)
Return values :
0 All ok.
-1 File not found.
-2 Syntax error.
-3 Command not found.
-------------------------------------------------------------------------------
Function CFinit
Prototype in cf.h
Module cf
Library tll
void CFinit(void)
Initialises the CF routines. Does not need to be called by the programmer
as all the CF routines check for initialisation at their start.
Parameters
none
Returns
nothing
-------------------------------------------------------------------------------
Function CFopen
Prototype in cf.h
Module cf
Library tll
int CFopen(char *s)
Open a configuration file for later use by CFread.
Parameters :
s Full pathname of config file. If <s> is NULL or empty, a file
with the program's name and ".cfg" extension is looked for,
first in the current directory, then the home directory. If <s>
is specified, only <s> is looked for.
Return Values :
0 Config file not found in any of the three locations.
1 User supplied filename found.
2 Found in current directory.
3 Found in home directory.
-------------------------------------------------------------------------------
Function CFread
Prototype in cf.h
Module cf
Library tll
int CFread(char *cmd,char *arg)
Read the next assignment statement from the config file (if open). If no
config file is currently open, return -1 (EOF). If an invalid statement is
encountered (positive return value), <cmd> will hold the entire line
containing the error, and <arg> will be empty. A maximum line size in the
config file of 80 characters is enforced (anything past this is truncated
internally). Thus, <cmd> and <arg> only need to be able to hold 81 chars.
An assignment statement is of the form
[<cmd> = <arg>] [#<comment>]
Note that all white space is ignored, empty lines and lines containing only
comments are valid, and anything after the first '#' on a line is treated
as a comment. <cmd> may only consist of alphanumeric characters, while
<arg> may consist of any character except '#'. As with <cmd>, all
whitespace is generally ignored when scanning <arg>, unless it is enclosed
in double quotes. Likewise, the '#' character may be included as part of
<arg> if it is enclosed in double quotes.
Parameters :
cmd Pointer to a character array at least 81 characters long. It
will hold the parameter name on return.
arg Pointer to a character array at least 81 characters long. It
will hold the parameter value on return.
Return Values :
-1 No more assignment statements available for reading from file.
0 Valid (cmd,arg) pair has been found.
1 Invalid characters found in the parameter name.
2 Syntax error in assignment statement.
-------------------------------------------------------------------------------
Function CFwrite
Prototype in cf.h
Module cf
Library tll
int CFwrite(char *f,CFdata *d)
The inverse of the CFread function. Opens the specified file, and
writes the contents of the specified CFdata structure to the file.
Parameters
f The file to write to.
d The data structure to write.
Returns
Zero if the write operation was successful, or -1 if it wasn't.
-------------------------------------------------------------------------------
Function DBadd
Prototype in db.h
Module db
Library dbl
int DBadd(void *r)
Adds the specified record to the currently active database file.
Parameters
r A pointer to the record to be added.
Returns
The record number at which the record was added if the operation was
successful, or -1 if it wasn't.
-------------------------------------------------------------------------------
Function DBbot
Prototype in db.h
Module db
Library dbl
int DBbot(void)
Returns the record number of the last record in the currently active
database file.
Parameters
None
Returns
The last record number if there is a currently active database file,
or -1 if there isn't.
-------------------------------------------------------------------------------
Function DBclose
Prototype in db.h
Module db
Library dbl
DBfile *DBclose(void)
This function closes the currently active database file, together with
it's index file. The new active database will be the last opened one.
If no other databases are open, there will be no active database.
Parameters
none
Returns
A pointer to the new active database, or NULL if there are no more
databases open.
-------------------------------------------------------------------------------
Function DBcmp
Prototype in db.h
Module db
Library dbl
int DBcmp(void *rs,void *rd)
Compares two areas of memory. The number of bytes compared is the
record size of the currently active database. The comparison returns
a value less than zero if the first area is less than the second, zero
if they are equal, or greater than zero if the first area is greater than
the second
Parameters
rs A pointer to the first area of memory.
rd A pointer to the second area of memory.
Returns
The result of the comparison, or zero if there is no currently
active database.
-------------------------------------------------------------------------------
Function DBcopy
Prototype in db.h
Module db
Library dbl
int DBcopy(void *rs,void *rd)
Copies one area of memory to another. The number of bytes copied is
the record size of the currently active database.
Parameters
rs A pointer to the area of memory to copy from.
rd A pointer to the area of memory to copy to.
Returns
The record size of the currently active database if there is one,
or zero if there isn't.
-------------------------------------------------------------------------------
Function DBdelete
Prototype in db.h
Module db
Library dbl
int DBdelete(void)
Deletes the record at the current record indicator in the currently active
database file.
Parameters
none
Returns
-1 in all cases.
-------------------------------------------------------------------------------
Function DBend
Prototype in db.h
Module db
Library dbl
void DBend(void)
Should not be called by the application. This function is called via
an 'atexit' call originated in DBopen. It closes all database and index
files in an orderly manner.
Parameters
none
Returns
nothing
-------------------------------------------------------------------------------
Function DBfindfirst
Prototype in db.h
Module db
Library dbl
int DBfindfirst(void *r)
Finds the first record in the currently active database which matches
the specified memory area.
Parameters
r A pointer to the memory area to find.
Returns
The record number it was found at, if it was, or -1 if either there
is no currently active database, or the record was not found.
-------------------------------------------------------------------------------
Function DBfindnext
Prototype in db.h
Module db
Library dbl
int DBfindnext(void *r)
Finds the next record in the currently active database which matches the
specified memory area. The search begins at the record succeeding the
current record. Generally used after DBfindfirst, but may be used at any
time.
Parameters
r A pointer to the memory area to find.
Returns
The record number it was found at, if it was, or -1 if either there
is no currently active database, or the record was not found.
-------------------------------------------------------------------------------
Function DBgo
Prototype in db.h
Module db
Library dbl
int DBgo(int r)
Moves the current record indicator to the specified record in the
currently active database.
Parameters
r The record number to move to. Range from 0 to the number of
database records - 1.
Returns
The new current record number if the move was successful, or -1 if
it wasn't. If the specified record was out of range, the current
record indicator will point to the requested record anyway, which
other functions will treat as either before the top, or after the
bottom, of the file, depending on whether the requested record was
less than zero, or greater than that allowed, respectively.
-------------------------------------------------------------------------------
Function DBiread
Prototype in db.h
Module db
Library dbl
int DBiread(int n)
Should not be called by the application program.
Reads an index record and returns the database record number it points
to.
Parameters:
n Index record number to read. Range from 0 to the number of
index records - 1.
Returns
The database record number (from 0 to the number of database records
- 1) if the index record number was valid, or -1 if it wasn't.
-------------------------------------------------------------------------------
Function DBiwrite
Prototype in db.h
Module db
Library dbl
int DBiwrite(int n,int datarec)
Should not be called by the application program.
Writes a value into the specified index record.
Parameters
n The index record to write to. Range from zero to the number
of index records in the file. If it equals the number of
index records, it implies an addition to the end of the index
file
datarec The value to write. Normally points to a record in the
database file, but may theoretically hold any value.
Returns
TRUE if the write was successful, or FALSE if it wasn't.
-------------------------------------------------------------------------------
Function DBopen
Prototype in db.h
Module db
Library dbl
DBfile *DBopen(char *fn,int rs,char *ifn,int (*func)(void *,void *))
Opens the specified database file and prepares it for access
according to the specified index file and function.
Parameters
fn Pathname of the database file.
rs Size of each record in the database file in bytes.
ifn Pathname of the index file.
func Comparison function.
Returns
A pointer to the DBfile structure (defined in db.h) for this
database, or NULL if the open failed.
-------------------------------------------------------------------------------
Function DBread
Prototype in db.h
Module db
Library dbl
int DBread(void *r)
Reads the current record from the active database into the memory area
pointed to by 'r'.
Parameters
r A pointer to the memory area to hold the file data.
Returns
The current record number if the read was successful, or -1 if it
wasn't.
-------------------------------------------------------------------------------
Function DBreadn
Prototype in db.h
Module db
Library dbl
int DBreadn(int rn,void *r)
Reads the specified record from the currently active database file into
the specified memory area.
Parameters
rn The record number to read.
r A pointer to the memory area to read into.
Returns
The record number read if successful, or -1 if not.
-------------------------------------------------------------------------------
Function DBrecno
Prototype in db.h
Module db
Library dbl
int DBrecno(void)
Returns the current record number in the currently active database.
Parameters
none
Returns
The record number if there is a currently active database, or -1 if
there isn't.
-------------------------------------------------------------------------------
Function DBseekfirst
Prototype in db.h
Module db
Library dbl
int DBseekfirst(void *r,int (*func)(void *,void *))
This function and DBseeknext are the same as findfirst and findnext,
except the programmer must supply the comparison function. This comparison
function must be a less exact (or as exact) version of the index function.
For instance, if the index function was based on a string comparison of all
characters in the surname, this function could be based on a string
comparison of part of the surname, but could not be based on a comparison
of the surname and the first name combined.
An example...
In an application program I've written, part of the database record is the
patient's surname. This field is also the sorting key for the database.
Thus, my index function compares the surname's, looking for an *exact*
match. However, the program allows the user to scan a list of all patients
matching a given template. The user types in the first few characters of
a surname, and a list is brought up showing all patients with surnames of
which the few characters are a subset. eg, SPE will match SPENCER, SPEND,
etc. To do this, I call the 'seek' functions with a function which returns
a match if the first string is a subset of the second. The critical point
is that, no matter what search algorithm I use within these routines, the
function parsed to 'seek' should be able to find all records given that
the database is indexed according to the function parsed to 'open'.
Make sense? Didn't think so. Doesn't make sense to me either, but it works.
Parameters
r A pointer to the memory area to find.
func A pointer to the comparison function to use.
Returns
The record number it was found at, if it was, or -1 if either there
is no currently active database, or the record was not found.
-------------------------------------------------------------------------------
Function DBseeknext
Prototype in db.h
Module db
Library dbl
int DBseeknext(void *r,int (*func)(void *,void *))
See DBseekfirst
Parameters
r A pointer to the memory area to find.
func A pointer to the comparison function to use.
Returns
The record number it was found at, if it was, or -1 if either there
is no currently active database, or the record was not found.
-------------------------------------------------------------------------------
Function DBselect
Prototype in db.h
Module db
Library dbl
void DBselect(DBfile *db)
Makes the specified database the active one.
Parameters
db A pointer to the DBfile structure for the desired database.
Returns
Nothing
-------------------------------------------------------------------------------
Function DBskip
Prototype in db.h
Module db
Library dbl
int DBskip(int n)
Moves the current record indicator for the currently active database
forward or backward the specified number of records. The move can be
off the top or bottom of the file, but no further. ie, it will not
cycle around from top to bottom or vice-versa.
Parameters
n The number of records to skip. A positive value will move
forward in the file, while a negative value will move
backward. A zero value will have no effect.
Returns
The new current record indicator if there is a currently active
database, or -1 if there isn't. Note that skipping past the top
or bottom of the file will return the Before-Top (-1) or After-Bottom
(too large) indicators.
-------------------------------------------------------------------------------
Function DBtop
Prototype in db.h
Module db
Library dbl
int DBtop(void)
Returns the record number of the first record in the currently active
database file.
Parameters
None
Returns
The first record number if there is a currently active database file,
or -1 if there isn't.
-------------------------------------------------------------------------------
Function DBvalid
Prototype in db.h
Module db
Library dbl
int DBvalid(void)
Returns the validity of the current record indicator in the currently
active database.
Parameters
none
Returns
TRUE if the current record indicator is valid, or FALSE if it isn't.
-------------------------------------------------------------------------------
Function DBwrite
Prototype in db.h
Module db
Library dbl
int DBwrite(void *r)
Writes the specified memory area to the current record in the currently
active database file.
Parameters
r A pointer to the record to write.
Returns
The current record number if the operation was successful, or -1 if
it wasn't.
-------------------------------------------------------------------------------
Function IFCallin
Prototype in ifc.h
Module ifc
Library tll
int16 IFCallin(void)
This function is similar to IFCin, except that it inputs from all 9
possible input pins instead of just 8. The bits in the returned value are :
Bit Pin
0 1
1 14
2 16
3 17
4 15
5 13
6 12
7 10
8 11
A ground on the given pin will return a 1 in the appropriate bit position,
while a 0 is returned if the pin is floating or tied to +5v. Note that
some of the pins are inverted. This is corrected in this routine by
exclusive-Oring the read value before returning. Also, to gain a valid
return value, the programmer should make sure the following function
call is made :
IFCallout(0x0400);
Since the lower 4 bits of the input value are taken from an open-collector
output chip, the chip must have the correct values output to it's pins
before reading. The above call accomplishes this. It also resets the
remaining output pins (lower 8 bits). This does not need to be done, as
long as bit 10 is set and bits 8,9 and 11 are reset.
Parameters
none
Returns
The bits read, or -1 if the port is not installed.
-------------------------------------------------------------------------------
Function IFCallout
Prototype in ifc.h
Module ifc
Library tll
int16 IFCallout(uint16 val)
This function is similar to IFCout, except that it outputs to all 12
possible output pins instead of just 8. The bits are output onto the
following pins :
Bit Pin
0 2
1 3
2 4
3 5
4 6
5 7
6 8
7 9
8 1
9 14
10 16
11 17
Parameters
val The binary value to ouput, of which the lower 12 bits are used.
Returns
The result of the output operation, as read from the port, or -1
if the port is not installed.
-------------------------------------------------------------------------------
Function IFCin
Prototype in ifc.h
Module ifc
Library tll
int16 IFCin(void)
This function reads the current status of eight input lines from the
current port, and returns the value. The bits in the returned value are :
Bit Pin
0 1
1 14
2 16
3 15
4 13
5 12
6 10
7 11
Note : Ground (relative to pin 25) on any pin will produce a 0 in the
corresponding bit position, while +5v will produce a 1. With
some printer boards, a floating pin will consistently produce
a 1, while with others it varies.
Parameters
none
Returns
The bits read, or -1 if the port is not installed.
-------------------------------------------------------------------------------
Function IFCout
Prototype in ifc.h
Module ifc
Library tll
int16 IFCout(uint8 val)
This function outputs the 8-bit value 'val' to the current port.
The bits are output onto the following pins :
Bit Pin
0 2
1 3
2 4
3 5
4 6
5 7
6 8
7 9
Note : A '1' in any bit position will produce +5v on the appropriate line,
while a '0' will drop it to ground, relative to pin 25. These
voltages will stay until a different value is written.
Parameters
val The binary value to output.
Returns
The result of the output operation, as read from the port, or -1
if the port is not installed.
-------------------------------------------------------------------------------
Function IFCset
Prototype in ifc.h
Module ifc
Library tll
int IFCset(int lpt)
This function sets the printer port to use. It simply checks for a valid
input value and sets IFClpt to that value. This value is used in the
functions 'IFCin' and 'IFCout'.
Parameters
lpt The port to use. Range from 0 (LPT1) to 3 (LPT4).
Returns
TRUE if the port is installed, FALSE if it isn't.
-------------------------------------------------------------------------------
Function KBcheck
Prototype in kb.h
Module kb
Library wnl
int KBcheck(void)
Checks to see whether a key has been pressed.
Parameters
none
Returns
TRUE if a key has been pressed, or FALSE if it hasn't.
-------------------------------------------------------------------------------
Function KBgetc
Prototype in kb.h
Module kb
Library wnl
uchar KBgetc(char *c,char *s,int f)
Gets a single character response from the keyboard. The key pressed is
stored in the location pointed to by 'c', and the valid reponses are
limited to characters in the string 's'. The flag 'f' determines the
characteristics of the input function as follows :
K_UPPER Convert all keystrokes to uppercase.
K_BELL Sound the console bell on an invalid response.
K_RETURN Return a <CR> for the function instead of the character.
The character is still stored in 'c'.
Parameters
c A pointer to the location to store the character.
s A pointer to a string containing valid characters.
f The flags above, ORed together.
Returns
The character entered, or <CR> if K_RETURN is set.
-------------------------------------------------------------------------------
Function KBgetch
Prototype in kb.h
Module kb
Library wnl
uchar KBgetch(void)
Wait for a keypress and return the key's value.
Parameters
none
Returns
The key pressed.
-------------------------------------------------------------------------------
Function KBgetn
Prototype in kb.h
Module kb
Library wnl
uchar KBgetn(double *n,uint w,uint d)
Gets a number from the keyboard at the current screen coordinates. Uses
the WN functions for displaying.
Parameters
n A pointer to the number to be edited (a double).
w The total width of the number to be edited, including the
decimal point.
d The number of decimal places in the number to be edited.
Returns
The last key pressed before exiting the function.
-------------------------------------------------------------------------------
Function KBgets
Prototype in kb.h
Module kb
Library wnl
uchar KBgets(char *s,uint l,int f)
Gets a string from the keyboard at the current screen coordinates.
Uses the WN functions for displaying. The only valid value for 'f' is
K_UPPER, which converts all keys to uppercase.
Parameters
s A pointer to the string to be edited.
l The length of the string to be edited.
f The flags.
Returns
The last key pressed before exiting the function.
-------------------------------------------------------------------------------
Function KBnwgetch
Prototype in kb.h
Module kb
Library wnl
uchar KBnwgetch()
Check to see whether a key has been pressed, and if so, return it's
value.
Parameters
none
Returns
The key pressed if there was one, or zero if there wasn't.
-------------------------------------------------------------------------------
Function KBsetfunc
Prototype in kb.h
Module kb
Library wnl
void KBsetfunc(void (*func)(void))
Sets the function to be called while waiting for a keypress.
Parameters
func The function to be called, or NULL for no function.
Returns
nothing
-------------------------------------------------------------------------------
Function KBsettrap
Prototype in kb.h
Module kb
Library wnl
void KBsettrap(uchar key,void (*func)(void))
Sets a key to be looked for while waiting for input, and a function to
be called if it's seen.
Parameters
key The key to look for.
func The function to call when it's found.
Returns
nothing
-------------------------------------------------------------------------------
Function KKend
Prototype in kk.h
Module kk
Library gml
void KKend(void)
Resets the vectors to the way they were originally.
Parameters
none
Returns
nothing
-------------------------------------------------------------------------------
Function KKget
Prototype in kk.h
Module kk
Library gml
int KKget(uchar scan)
Returns the current state of the key with the specified scan code.
Parameters
scan The scan code of the key to check.
Returns
TRUE if the key is currently pressed, or FALSE if it isn't.
-------------------------------------------------------------------------------
Function KKhandler
Prototype in kk.h
Module kk
Library gml
void interrupt KKhandler(void)
This is the new interrupt 9 handler. It merely sets or resets the
appropriate byte in the keyboard table, based on the scan code presented.
There is a call to the old interrupt 9 handler commented out. This is
because I assume that if you are using this one, you don't want normal
keyboard actions (such as the buffer filling since you're not reading it)
to occur. If you want them to, remove the comments around the 'old09()'
statement, and place them around the 'kbreset()' statement. This may be
implemented as a parameter to 'newkeyinit()' later.
Parameters
none
Returns
nothing
-------------------------------------------------------------------------------
Function KKinit
Prototype in kk.h
Module kk
Library gml
void KKinit(void)
Initialises the new keyboard handler. First checks the value of 'old09'
to make sure it hasn't already been called. Then sets vectors, and does
an 'atexit' call to make sure the vectors are swapped back before exiting
the program. The 'newkeyend()' function can be called explicitly, as it
also checks the value of 'old09'. The 'atexit' function could be removed,
as long as you remember to call 'newkeyend' yourself. Also, this function
zeroes the current contents of the keyboard flags buffer.
Parameters
none
Returns
nothing
-------------------------------------------------------------------------------
Function KKreset
Prototype in kk.h
Module kk
Library gml
void KKreset(uchar scan)
Sets the flag for the specified key to FALSE
Parameters
scan The scan code of the key to set.
Returns
nothing
-------------------------------------------------------------------------------
Function KKset
Prototype in kk.h
Module kk
Library gml
void KKset(uchar scan)
Sets the flag for the specified key to TRUE
Parameters
scan The scan code of the key to set.
Returns
nothing
-------------------------------------------------------------------------------
Function MNcolor
Prototype in mn.h
Module mn
Library wnl
void MNcolor(uint norm,uint high)
Set the menu colors. 'n' specifies the normal text color,
and 'h' the highlighted text color.
Parameters
norm The normal menu color.
high The highlighted menu color.
Returns
nothing
-------------------------------------------------------------------------------
Function MNmenu
Prototype in mn.h
Module mn
Library wnl
uchar MNmenu(MNdata *mn)
Initiate the menu system, from the data pointed to by 'mn'.
Parameters
mn A pointer to the MNdata structure defined in mn.h holding
the menu definition.
Returns
The last character entered before terminating this function.
-------------------------------------------------------------------------------
Function MNselect
Prototype in mn.h
Module mn
Library wnl
uchar MNselect(uint ncolor,uint hcolor,int min,int max,int *option,
void (*func)(uint,uint))
Select an item from a list.
Parameters
ncolor The color to use for normal text.
hcolor The color to use for highlighted text.
min The lowest valid value for 'option'.
max The highest valid value for 'option'.
option A pointer to an integer which holds the current item number on
entry to this function, and the selected item on exit.
func A pointer to the function which displays the current item.
Returns
The last character entered before terminating this function.
-------------------------------------------------------------------------------
Function PKaccess_type
Prototype in pk.h
Module pk
Library netl
int PKaccess_type(int if_class,int if_type,int if_number,char far *type,
uint typelen,void interrupt (*receiver)())
Initiates access to packets of the specified type. The argument type is a
pointer to a packet type specification. The argument typelen is the length
in bytes of the type field. The argument receiver is a pointer to a
subroutine which is called when a packet is received. If the typelen
argument is 0, this indicates that the caller wants to match all packets
(match all requests may be refused by packet drivers developed to conform
to versions of this spec previous to 1.07).
When a packet is received, receiver is called twice by the packet driver.
The first time it is called to request a buffer from the application to
copy the packet into. AX == 0 on this call. The application should return
a pointer to the buffer in ES:DI. If the application has no buffers, it
may return 0:0 in ES:DI, and the driver should throw away the packet and
not perform the second call.
It is important that the packet length (CX) be valid on the AX == 0 call,
so that the receiver can allocate a buffer of the proper size. This length
(as well as the copy performed prior to the AX == 1 call) must include the
MAC header and all received data, but not the trailing Frame Check Sequence
(if any).
On the second call, AX == 1. This call indicates that the copy has been
completed, and the application may do as it wishes with the buffer. The
buffer that the packet was copied into is pointed to by DS:SI.
Parameters
if_class Class of the interface.
if_type Type of the interface.
if_number Number of the interface.
type Pointer to the desired packet type.
typelen Length of the desired packet type.
receiver Pointer to function to call on receipt of an incoming
packet.
Returns
AX register if operation successful, or -1 if it wasn't.
Possible errors
NO_CLASS
NO_TYPE
NO_NUMBER
BAD_TYPE
NO_SPACE
TYPE_INUSE
-------------------------------------------------------------------------------
Function PKas_send_pkt
Prototype in pk.h
Module pk
Library netl
int PKas_send_pkt(char far *buf,uint len,
void interrupt (*upcall)(int result,char far *buffer))
as_send_pkt() differs from send_pkt() in that the upcall() routine is
called when the application's data has been copied out of the buffer, and
the application can safely modify or re-use the buffer. The driver may
pass a non-zero error code to upcall() if the copy failed, or some other
error was detected, otherwise it should indicate success, even if the
packet hasn't actually been transmitted yet. Note that the buffer passed
to send_pkt() is assumed to be modifiable when that call returns, whereas
with as_send_pkt(), the buffer may be queued by the driver and dealt with
later. If an error is returned on the initial call, the upcall will not be
executed. This function was added in v1.09 of this specification, and may
not be implemented by all drivers (see driver_info()).
The upcall() routine is called with the status in AX, and a pointer to the
original buffer area in ES:DI.
Parameters
buf Pointer to the area containing the data to transmit.
len Length of the data to transmit.
upcall Function to call when buffer re-usable.
Returns
TRUE if the operation was successful, or FALSE if it wasn't.
Possible errors
CANT_SEND (transmit error, re-entered, etc.)
BAD_COMMAND (Level 0 or 1 driver)
-------------------------------------------------------------------------------
Function PKcheck_int
Prototype in pk.h
Module pk
Library netl
int PKcheck_int(int intnum)
Checks for the existence of a packet driver at the spcified interrupt
vector.
Parameters
intnum The interrupt vector to check.
Returns
TRUE if there is a driver at that vector, or FALSE if there isn't.
-------------------------------------------------------------------------------
Function PKdriver_info
Prototype in pk.h
Module pk
Library netl
PKinfo far *PKdriver_info(int handle)
This function returns information about the interface. The version is
assumed to be an internal hardware driver identifier. In earlier versions
of this spec, the handle argument (which must have been obtained via
access_type()) was required. It is now optional, but drivers developed
according to versions of this spec previous to 1.07 may require it, so
implementers should take care.
Parameters
handle Handle returned from access_type.
Returns
Pointer to a locally declared static PKinfo structure defined in pkt.h
containing the information if available, or NULL if not. This structure
is overwritten with each call to this function.
Possible errors
BAD_HANDLE (older drivers only)
-------------------------------------------------------------------------------
Function PKerror
Prototype in pk.h
Module pk
Library netl
void PKerror(int err)
Generates an error condition. If 'err' == 0, the last error returned
from the driver is used, else 'err' is used to indicate the type of error.
The interface functions within this module always pass '0', but the user
program may wish to pass some other value to simulate an error. Also,
if the error was not generated by the packet driver (as in the case of
the initialise() function), PKerror can be called with a non-zero value.
Parameters
err The error number to generate, or 0 to generate the last
error from the driver.
Returns
Nothing
-------------------------------------------------------------------------------
Function PKget_address
Prototype in pk.h
Module pk
Library netl
int PKget_address(int handle,char far *buf,int len)
Copies the current local net address of the interface into buf. The buffer
buf is len bytes long. The actual number of bytes copied is returned in
CX. If the NO_SPACE error is returned, this indicates that len was
insufficient to hold the local net address. If the address has been changed
by set_address(), the new address should be returned.
Parameters
handle Handle returned from access_type.
buf Pointer to area to store address in.
len Maximum length of area.
Returns
The number of bytes copied if successful, or zero if not.
Possible errors
BAD_HANDLE
NO_SPACE
-------------------------------------------------------------------------------
Function PKget_multicast_list
Prototype in pk.h
Module pk
Library netl
int PKget_multicast_list(char far *addrlist)
On a successful return, addrlst points to len bytes of multicast addresses
currently in use. The application program must not modify this information
in-place. A NO_SPACE error indicates that there wasn't enough room for all
active multicast addresses.
Parameters
addrlist Pointer to an area to hold the multicast address list.
Returns
The number of bytes copied if the operation was successful, or zero
if it wasn't. The multicast address list is copied into the area
pointed to by addrlist if possible.
Possible errors
NO_MULTICAST
NO_SPACE
-------------------------------------------------------------------------------
Function PKget_parameters
Prototype in pk.h
Module pk
Library netl
PKparam far *PKget_parameters(void)
The performance of an application may benefit from using get_parameters()
to obtain a number of driver parameters. This function was added to v1.09
of this specification, and may not be implemented by all drivers (see
driver_info()).
The major_rev and minor_rev fields are the major and minor revision numbers
of the version of this specification the driver conforms to. For this
document, major_rev is 1 and minor_rev is 9. The length field may be used
to determine which values are valid, should a later revision of this
specification add more values at the end of this structure. For this
document, length is 14. The addr_len field is the length of a MAC address,
in bytes. Note the param structure is assumed to be packed, such that these
fields occupy four consecutive bytes of storage.
In the param structure, the mtu is the maximum MAC-level packet the driver
can handle (on Ethernet this number is fixed, but it may vary on other
media, e.g. 802.5 or FDDI). The multicast_aval field is the number of
bytes required to store all the multicast addresses supported by any
"perfect filter" mechanism in the hardware. Calling set_multicast_list()
with its len argument equal to this value should not fail with a NO_SPACE
error. A value of zero implies no multicast support.
The rcv_bufs and xmt_bufs indicate the number of back-to-back receives or
transmits the card/driver combination can accomodate, minus 1. The
application can use this information to adjust flow-control or transmit
strategies. A single-buffered card (for example, an Interlan NI5010) would
normally return 0 in both fields. A value of 0 in rcv_bufs could also be
used by a driver author to indicate that the hardware has limitations which
prevent it from receiving as fast as other systems can send, and to
recommend that the upper-layer protocols invoke lock-step flow control to
avoid packet loss.
The int_num field should be set to a hardware interrupt that the
application can hook in order to perform interrupt-time protocol processing
after the EOI has been sent to the 8259 interrupt controller and the card
is ready for more interrupts. A value of zero indicates that there is no
such interrupt. Any application hooking this interrupt and finding a non-
zero value in the vector must pass the interrupt down the chain and wait
for its predecessors to return before performing any processing or stack
switches. Any driver which implements this function via a separate INT
instruction and vector, instead of just using the hardware interrupt, must
prevent any saved context from being overwritten by a later interrupt. In
other words, if the driver switches to its own stack, it must allow re-
entrancy.
Parameters
none
Returns
Pointer to a locally declared static PKparam structure defined in pkt.h
containing the information if available, or NULL if not. This structure
is overwritten with each call to this function.
Possible errors
BAD_COMMAND (No high-performance support)
-------------------------------------------------------------------------------
Function PKget_rcv_mode
Prototype in pk.h
Module pk
Library netl
int PKget_rcv_mode(int handle)
Returns the current receive mode of the interface associated with handle.
Parameters
handle Handle returned from access_type.
Returns
The receive mode if available, or -1 if not.
Possible errors
BAD_HANDLE
-------------------------------------------------------------------------------
Function PKget_statistics
Prototype in pk.h
Module pk
Library netl
PKstat far *PKget_statistics(int handle)
Returns a pointer to a statistics structure for the interface. The values
are stored as to be normal 80xx 32-bit integers.
Parameters
handle Handle returned from access_type.
Returns
Pointer to a locally declared static PKstat structure defined in pkt.h
containing the information if available, or NULL if not. This structure
is overwritten with each call to this function.
Possible errors
BAD_HANDLE
-------------------------------------------------------------------------------
Function PKinit
Prototype in pk.h
Module pk
Library netl
int PKinit(void)
Sets up internal variables for the driver functions to use. Must be
called prior to calling any other routines in this module.
Parameters
none
Returns
The interrupt number for the packet driver if one was found, or
zero if there isn't one.
-------------------------------------------------------------------------------
Function PKrelease_type
Prototype in pk.h
Module pk
Library netl
int PKrelease_type(int handle)
This function ends access to packets associated with a handle returned by
access_type(). The handle is no longer valid.
Parameters
handle Handle returned from access_type.
Returns
TRUE if the operation was successful, or FALSE if it wasn't.
Possible errors
BAD_HANDLE
-------------------------------------------------------------------------------
Function PKreset_interface
Prototype in pk.h
Module pk
Library netl
int PKreset_interface(int handle)
Resets the interface associated with handle to a known state, aborting any
transmits in process and reinitializing the receiver. The local net address
is reset to the default (from ROM), the multicast list is cleared, and the
receive mode is set to 3 (own address & broadcasts). If multiple handles
are open, these actions might seriously disrupt other applications using
the interface, so CANT_RESET should be returned.
Parameters
handle Handle returned from access_type.
Returns
TRUE if the operation was successful, or FALSE if it wasn't.
Possible errors
BAD_HANDLE
CANT_RESET
-------------------------------------------------------------------------------
Function PKsend_pkt
Prototype in pk.h
Module pk
Library netl
int PKsend_pkt(char far *buf,uint len)
Transmits length bytes of data, starting at buffer. The application must
supply the entire packet, including local network headers. Any MAC or LLC
information in use for packet demultiplexing (e.g. the DEC-Intel-Xerox
Ethertype) must be filled in by the application as well. This cannot be
performed by the driver, as no handle is specified in a call to the
send_packet() function.
Parameters
buf Pointer to the data to be sent.
len Length of the data to be sent.
Returns
TRUE if the operation was successful, or FALSE if it wasn't.
Possible errors
CANT_SEND
-------------------------------------------------------------------------------
Function PKset_address
Prototype in pk.h
Module pk
Library netl
int PKset_address(char far *addr,int len)
This call is used when the application or protocol stack needs to use a
specific LAN address. For instance, DECnet protocols on Ethernet encode
the protocol address in the Ethernet address, requiring that it be set when
the protocol stack is loaded. A BAD_ADDRESS error indicates that the
Packet Driver doesn't like the len (too short or too long), or the data
itself. Note that packet drivers should refuse to change the address (with
a CANT_SET error) if more than one handle is open (lest it be changed out
from under another protocol stack).
Parameters
addr Pointer to the address to be set.
len Length of the address to be set.
Returns
The number of bytes actually copied if the operation was successful,
or zero if it wasn't.
Possible errors
CANT_SET
BAD_ADDRESS
-------------------------------------------------------------------------------
Function PKset_multicast_list
Prototype in pk.h
Module pk
Library netl
int PKset_multicast_list(char far *addrlist,int len)
The addrlst argument is assumed to point to an len-byte buffer containing a
number of multicast addresses. BAD_ADDRESS is returned if len modulo the
size of an address is not equal to 0, or the data is unacceptable for some
reason. NO_SPACE is returned (and no addresses are set) if there are more
addresses than the hardware supports directly.
The recommended procedure for setting multicast addresses is to issue a
get_multicast_list(), copy the information to a local buffer, add any
addresses desired, and issue a set_multicast_list(). This should be
reversed when the application exits. If the set_multicast_list() fails due
to NO_SPACE, use set_rcv_mode() to set mode 5 instead.
Parameters
addrlist Pointer to the multicast address list.
len Length of the multicast address list.
Returns
TRUE if the operation was successful, or FALSE if it wasn't.
Possible errors
NO_MULTICAST
NO_SPACE
BAD_ADDRESS
-------------------------------------------------------------------------------
Function PKset_rcv_mode
Prototype in pk.h
Module pk
Library netl
int PKset_rcv_mode(int handle,int mode)
Sets the receive mode on the interface associated with handle. The
following values are accepted for mode:
mode meaning
1 turn off receiver
2 receive only packets sent to this interface
3 mode 2 plus broadcast packets
4 mode 3 plus limited multicast packets
5 mode 3 plus all multicast packets
6 all packets
Note that not all interfaces support all modes. The receive mode affects
all packets received by this interface, not just packets associated with
the handle argument. See the extended driver functions
get_multicast_list() and set_multicast_list() for programming "perfect
filters" to receive specific multicast addresses.
Note that mode 3 is the default, and if the set_rcv_mode() function is not
implemented, mode 3 is assumed to be in force as long as any handles are
open (from the first access_type() to the last release_type()).
Parameters
handle Handle returned from access_type.
mode Desired receive mode.
Returns
TRUE if the operation was successful, or FALSE if it wasn't.
Possible errors
BAD_HANDLE
BAD_MODE
-------------------------------------------------------------------------------
Function PKseterr
Prototype in pk.h
Module pk
Library netl
void PKseterr(void (*func)())
Sets the function to be called when an error condition is generated.
Whenever PKerror is called, it checks to see if a function has been
set, and calls it with the error number and the appropriate error
string as parameters. The function should be declared as one of the
following :
void func(void);
void func(char *errstring);
void func(char *errstring,int errnumber);
It has been designed this way so that, in the simplest case, the command
PKseterror(puts) will cause any error messages to be simply displayed on
standard output. However, the application program can define and specify
a more complex function using both parameters if required.
Parameters
func The function to be called when an error is generated.
Returns
Nothing
-------------------------------------------------------------------------------
Function PKterminate
Prototype in pk.h
Module pk
Library netl
int PKterminate(int handle)
Terminates the driver associated with handle. If possible, the driver will
exit and allow MS-DOS to reclaim the memory it was using.
Parameters
handle Handle returned from access_type.
Returns
TRUE if the operation was successful, or FALSE if it wasn't.
Possible errors
BAD_HANDLE
CANT_TERMINATE
-------------------------------------------------------------------------------
Function PRerror
Prototype in pr.h
Module pr
Library tll
void PRerror(int n)
Called by other PR functions to generate an error condition. Can also be
called by the programmer to simulate a printer error.
Parameters
n The error number to generate.
Returns
nothing
-------------------------------------------------------------------------------
Function PRprintf
Prototype in pr.h
Module pr
Library tll
int PRprintf(char *fmt,...)
Outputs the specified variables to the printer according to the format
string. The format specification is the same as for printf etc.
Parameters
fmt The format string.
... The variables to print.
Returns
The number of characters output, or EOF if an error occurred.
-------------------------------------------------------------------------------
Function PRputs
Prototype in pr.h
Module pr
Library tll
int PRputs(char *s)
Outputs the specified string to the printer. Attempts to do it's own
checking of the printer to remove those nasty DOS critical error
messages. Works well enough, but I'm still not real happy with it.
Expect some changes to be made here.
Parameters
s The string to output
Returns
The last character output, or EOF if an error occurred.
-------------------------------------------------------------------------------
Function PRseterr
Prototype in pr.h
Module pr
Library tll
void PRseterr(void (*func)(char *))
Sets the function to be called when a printer error is generated. The
function should expect a pointer to a character string containing the
error message.
Parameters
func A pointer to the function to call.
Returns
nothing
-------------------------------------------------------------------------------
Function SCclear
Prototype in sc.h
Module sc
Library wnl
int SCclear(SCdata *sc)
Clears the fields on the screen defined in 'sc'.
-------------------------------------------------------------------------------
Function SCdisplay
Prototype in sc.h
Module sc
Library wnl
int SCdisplay(SCdata *f)
Displays the field pointed to by 'f'.
-------------------------------------------------------------------------------
Function SCgetfield
Prototype in sc.h
Module sc
Library wnl
uchar SCgetfield(SCdata *f)
Gets the field pointed to by 'f'.
-------------------------------------------------------------------------------
Function SCgetscreen
Prototype in sc.h
Module sc
Library wnl
uchar SCgetscreen(SCdata *sc,int *cf)
Gets a screen of data from the user, using the array of field
structures pointed to by 'sc'. On entry, the current field is
set to 'cf', and on exit, 'cf' is set to the current field.
-------------------------------------------------------------------------------
Function SCnf
Prototype in sc.h
Module sc
Library wnl
int SCnf(SCdata *sc)
Returns the number of fields in the screen pointed to by 'sc'.
-------------------------------------------------------------------------------
Function SCshow
Prototype in sc.h
Module sc
Library wnl
int SCshow(SCdata *sc)
Displays the current screen defined by 'sc'.
-------------------------------------------------------------------------------
Function WNback
Prototype in wn.h
Module wn
Library wnl
void WNback(int c)
Set the current window background color to 'c'.
-------------------------------------------------------------------------------
Function WNbox
Prototype in wn.h
Module wn
Library wnl
void WNbox(int lef,int top,int rig,int bot,int type)
Draw a box from 'ulx','uly' to 'lrx','lry'. Box can be single
or double lined, as specified in 'attr'. 0 is single, 1 is
double.
-------------------------------------------------------------------------------
Function WNclose
Prototype in wn.h
Module wn
Library wnl
WNwin *WNclose(void)
Close the current window and select the last opened window.
Removes the window from the screen if it was opened as a
popup window.
-------------------------------------------------------------------------------
Function WNcolor
Prototype in wn.h
Module wn
Library wnl
int WNcolor(int c)
Set the current window color to 'c'.
-------------------------------------------------------------------------------
Function WNcursor
Prototype in wn.h
Module wn
Library wnl
void WNcursor(int state)
Place the cursor at the absolute position 'posn'. 'posn' is
a value returned from WNgcursor.
-------------------------------------------------------------------------------
Function WNdisplay
Prototype in wn.h
Module wn
Library wnl
void WNdisplay(int x,int y,char *mess)
Display the string pointed to by 's' in the current window
at coordinates 'x','y'.
-------------------------------------------------------------------------------
Function WNend
Prototype in wn.h
Module wn
Library wnl
void WNend(void)
Close all windows and restore the DOS screen present before
WNinit was called. Should not be called by the programmer,
as it is set up as an 'atexit' function by WNinit.
-------------------------------------------------------------------------------
Function WNfore
Prototype in wn.h
Module wn
Library wnl
void WNfore(int c)
Set the current window foreground color to 'c'.
-------------------------------------------------------------------------------
Function WNgcursor
Prototype in wn.h
Module wn
Library wnl
int WNgcursor(void)
Get the current absolute cursor position.
-------------------------------------------------------------------------------
Function WNhline
Prototype in wn.h
Module wn
Library wnl
void WNhline(int l,int r,int y,int f)
Draws a horizontal line (single or double) from l,y to r,y.
Parameters
l The left x-position of the line.
r The right x-position of the line.
y The y-position of the line.
f 0 for a single line, or 1 for a double.
Returns
nothing
-------------------------------------------------------------------------------
Function WNinit
Prototype in wn.h
Module wn
Library wnl
void WNinit(void)
Initialise the Windowing System. Does not need to be called
by the programmer as all WN functions check for it first.
-------------------------------------------------------------------------------
Function WNload
Prototype in wn.h
Module wn
Library wnl
void WNload(void)
Sets up window limits, screen color, and cursor position and
type as specified by the current window.
There are 4 things to be restored on entry to a window. The window
coordinates, the cursor position, the color, and the cursor type.
-------------------------------------------------------------------------------
Function WNloadcurs
Prototype in wn.h
Module wn
Library wnl
void WNloadcurs(void)
Returns the cursor to the position previously saved by
WNsavecurs.
Set the current cursor position from two static variables (cursx,cursy).
These variables can only be seen within this module.
-------------------------------------------------------------------------------
Function WNloaddos
Prototype in wn.h
Module wn
Library wnl
void WNloaddos(void)
Restore the DOS screen.
-------------------------------------------------------------------------------
Function WNmessage
Prototype in wn.h
Module wn
Library wnl
void WNmessage(WNwin *win,int x,int y,int c,char *mess)
Place the character string 's' at the position 'x','y' in
the color 'c' in window 'w'.
-------------------------------------------------------------------------------
Function WNopen
Prototype in wn.h
Module wn
Library wnl
WNwin *WNopen(int ulx,int uly,int lrx,int lry,int color,int attr,char *tit)
Open a window from 'ulx','uly' to 'lrx','lry'. Current
color is set to 'c', and attributes to 'attr'. 'attr' can
specify whether the window is a popup or not, as well as
the border style (None, single or double).
-------------------------------------------------------------------------------
Function WNputc
Prototype in wn.h
Module wn
Library wnl
void WNputc(char ch)
Place the character 'c' in the current window.
-------------------------------------------------------------------------------
Function WNsave
Prototype in wn.h
Module wn
Library wnl
void WNsave(void)
Save the current window parameters.
These are the only two variables not updated on an ongoing basis by
these routines. All of the display functions use the Turbo-C console
I/O routines, which can change the cursor position without updating
the xy coordinates stored in the 'curr' structure.
-------------------------------------------------------------------------------
Function WNsavecurs
Prototype in wn.h
Module wn
Library wnl
void WNsavecurs(void)
Save the current cursor position to be restored later by
WNloadcurs.
Save the current cursor position into two static variables (cursx,cursy).
These variables can only be seen within this module.
-------------------------------------------------------------------------------
Function WNsavedos
Prototype in wn.h
Module wn
Library wnl
void WNsavedos(void)
Save the current DOS screen. Used in WNinit.
-------------------------------------------------------------------------------
Function WNselect
Prototype in wn.h
Module wn
Library wnl
WNwin *WNselect(WNwin *win)
Make the window pointed to by 'w' the current window.
-------------------------------------------------------------------------------
Function WNvline
Prototype in wn.h
Module wn
Library wnl
void WNvline(int t,int b,int x,int f)
Draws a vertical line (single or double) from x,t to x,b.
Parameters
t The top y-position of the line.
b The bottom y-position of the line.
x The x-position of the line.
f 0 for a single line, or 1 for a double.
Returns
nothing
-------------------------------------------------------------------------------
Function binary
Prototype in misc.h
Module misc
Library tll
char *binary(uint16 val,int digits)
Decodes a 16-bit integer into a character string up to 16 bytes long
(plus one byte for the terminating NULL) containing the ASCII
representation of the integer in binary. 'digits' specifies the number
of bits to decode. Eg, if 'val' was 25, and 'digits' was 8, the function
would return a pointer to a string consisting of "00011001". This string
is a locally declared static variable, and is overwritten with each call.
Parameters
val The integer to convert.
digits The number of bits to convert.
Returns
A pointer to the converted string.
-------------------------------------------------------------------------------
Function chkdrive
Prototype in disk.h
Module disk
Library tll
int chkdrive(int drive)
Check to see if the specified drive is valid. Works for all floppy
disks, hard disks, and network drives.
Thanks to marty@Shiva.COM (Marty Del Vecchio) for the idea, and
valley@gsbsun.uchicago.edu (Doug Dougherty) for the code, on which
this implementation is based.
Parameters
drive The drive to check (Range 'a'-'z' or 'A'-'Z').
Eg, chkdrive('A') or chkdrive('a') to see if drive 'A:'
is valid.
Returns
TRUE if the drive is valid, or FALSE if it isn't.
-------------------------------------------------------------------------------
Function datelong
Prototype in date.h
Module date
Library tll
long datelong(datest *d)
Given a pointer to a 'datest' structure, return the Day number of the
specified date(1-11967900). The datest structure contains the
year(1-32767), the month(1-12), and the day(1-31).
Day 1, Month 1, Year 1 is Day number 1.
-------------------------------------------------------------------------------
Function daynam
Prototype in date.h
Module date
Library tll
char *daynam(int d)
Returns a pointer to the 3-letter day name corresponding to the
day number parsed. Eg, 1 returns "Sun".
-------------------------------------------------------------------------------
Function dayname
Prototype in date.h
Module date
Library tll
char *dayname(int d)
Returns a pointer to the full day name corresponding to the
day number parsed. Eg, 1 returns "Sunday".
-------------------------------------------------------------------------------
Function daysuff
Prototype in date.h
Module date
Library tll
char *daysuff(int d)
Returns a pointer to the 2-letter suffix which should be appended to the
day number parsed. Eg, 21 returns "st".
-------------------------------------------------------------------------------
Function delenvp
Prototype in env.h
Module env
Library tll
int delenvp(char *var)
Delete a variable from the root environment.
Parameters
var The variable to delete.
Returns
TRUE if the variable was deleted, FALSE if it wasn't found.
-------------------------------------------------------------------------------
Function dice
Prototype in random.h
Module random
Library tll
int dice(int n,int d)
Rolls a 'd' sided dice 'n' times, summing the results. Eg, dice(4,6)
simulates the rolling of 4 6-sided dice, returning a number from 4 to 24.
Parameters
n The number of dice to roll.
d The number of sides on each dice.
Returns
The sum of the result of the rolls.
-------------------------------------------------------------------------------
Function endtrap
Prototype in misc.h
Module misc
Library tll
void endtrap(void)
Turns off BREAK key checking. See trapbreak.
Parameters
none
Returns
nothing
-------------------------------------------------------------------------------
Function farcmp
Prototype in far.h
Module far
Library tll
int farcmp(char far *s1,char far *s2,int n)
Compares two "far" strings. Returns TRUE or FALSE rather than a proper
comparison. This will be fixed in a future version. I'm not even sure this
is the right way to implement these functions, as it makes the libraries
dependent on this one (any that use these functions), and I'd like to keep
them completely independent.
Parameters
s1 The first string to compare.
s2 The second string to compare.
n The maximum number of bytes to compare.
Returns
TRUE if the strings are identical, or FALSE if they aren't.
-------------------------------------------------------------------------------
Function farmov
Prototype in far.h
Module far
Library tll
void farmov(char far *s1,char far *s2,int n)
Copies one "far" string to another. See 'farcmp' for more info.
Parameters
s1 The string to copy from.
s2 The string to copy to.
n The maximum number of bytes to copy.
Returns
nothing
-------------------------------------------------------------------------------
Function fndenvp
Prototype in env.h
Module env
Library tll
void fndenvp(void)
Locate the root environment, and set some variables for use by other
functions in this module.
Parameters
none
Returns
nothing
-------------------------------------------------------------------------------
Function getarg
Prototype in arg.h
Module arg
Library tll
char *getarg(void)
Gets succesive arguments from the command line. If called before a 'getopt'
will get all arguments, including options. However, it is designed to be
used after a 'getopt'. Each call to getarg will return the next argument
on the command line.
Parameters
none
Returns
A pointer to the next command line argument, or NULL if there are none.
-------------------------------------------------------------------------------
Function getopt
Prototype in arg.h
Module arg
Library tll
void getopt(char *opts,...)
Interprets command line arguments according to the rules specified in
the string 'opts'. It uses the external variable '_argv', which is a
pointer to the command line argument array, to get the command line
arguments. The string 'opts' consists of a sequence of alphanumeric
characters, each one optionally followed by a non-alphanumeric character.
Each alphanumeric specifies a valid option. If it is followed by a colon,
the option may have an argument. If it is followed by any other non-
alphanumeric, the option may still have an argument, but the argument will
be appended to the storage area for that option, with the specified
non-alphanumeric character as a seperator.
The string 'opts' should be followed by a series of pointers to locations
to hold the data. There should always be exactly the same number of
pointers as characters in 'opts'. Each alphanumeric character should have
a corresponding pointer to an integer to hold the number of times that
option was specified on the command line, and each non-alphanumeric
character should have a pointer to a character array to hold the argument
following the option (if any). Any of the pointers may be NULL, indicating
that the corresponding value should not be stored.
Getopt makes any found argument or option into a null-string. Thus, getarg
can be called after getopt to return any remaining arguments.
An example of use would be good...
void main(void)
{
int opt_a,opt_b;
char arg_c[81];
char *s;
getopt("ab:c;",&opt_a,&opt_b,NULL,NULL,arg_c);
printf("Option a was entered %d times\r\n",opt_a);
printf("Option b was entered %d times\r\n",opt_b);
printf("Option c had arguments %s\r\n",arg_c);
while (s = getarg())
printf("Argument = %s\r\n");
}
This program would accept and count the number of occurrences of '-a' on
the command line, and the same for '-b'. Any arguments following a '-b'
would be ignored. Each occurrence of '-c' would have it's argument appended
to 'arg_c', with ';' as the seperator character.
Parameters
opts The specification string
... A list of pointers to either integers or character strings.
Returns
nothing
-------------------------------------------------------------------------------
Function getshftstate
Prototype in misc.h
Module misc
Library tll
int getshftstate(void)
This function returns the current state of the shift keys. At the moment
it merely reflects what BIOS thinks they are. If you have not been
chaining to the BIOS keyboard handler (because you have your own installed)
this function may return incorrect values.
The following four values are defined in misc.h for use in determining
whether a given shift key is depressed :
RSHIFT 0x01
LSHIFT 0x02
CTRL 0x04
ALT 0x08
To determine if a given key is pressed, AND the result of getshftstate
with the corresponding value. Eg, (getshftstate() & CTRL) will return
TRUE if the CTRL key is currently pressed.
Parameters
none
Returns
The current state of the shift keys, as follows :
Bit 0 Right Shift Key (1=pressed)
Bit 1 Left Shift Key (1=pressed)
Bit 2 Control Key (1=pressed)
Bit 3 Alt Key (1=pressed)
Bit 4 Scroll-Lock status (1=on)
Bit 5 Num-Lock status (1=on)
Bit 6 Caps-Lock status (1=on)
Bit 7 Insert status (1=on)
-------------------------------------------------------------------------------
Function kbreset
Prototype in misc.h
Module misc
Library tll
void kbreset(void)
This resets the keyboard after a scan-code has been sent, and sends an
EOI to the 8259 controller. This function is normally done by the old
interrupt 9 handler, but if it your handler does not chain to the old
interrupt handler, then this function must be called before exiting.
Parameters
none
Returns
nothing
-------------------------------------------------------------------------------
Function leapyear
Prototype in date.h
Module date
Library tll
int leapyear(int y)
Given a year(1-32767), return non-zero (TRUE) if it is a leapyear,
zero (FALSE) if it is not.
Uses the following rules :
If a year is evenly divisible by 4, it is a leapyear, unless it is
evenly divisible by 100 and not 400.
eg, 0, 4, 8, etc are leapyears.
100, 200, 300 are not leapyears.
400, 800, 1200, etc are leapyears.
-------------------------------------------------------------------------------
Function locks
Prototype in misc.h
Module misc
Library tll
uint8 locks(uint8 on,uint8 off)
Change the status of the num-lock, scroll-lock and caps-lock keys. At this
stage, this function merely updates the BIOS record. At some point, BIOS
updates the keyboard leds. I think this is only during keyboard or screen
I/O. I ran a batch file to call this function repeatedly, and it worked
while echo was on, but crashed the machine otherwise, so Handle With Care.
Note that OFF parameters take precedence over ON. Thus,
locks( L_SCR|L_NUM , L_NUM|L_CAP )
will turn the Scroll-lock key on, and both the Num-lock and Caps-lock
keys off. Also, since locks returns the current state of the lock keys,
and locks(0,0) will change nothing, it can be used to determine the
current state.
Parameters
on Bitwise OR of the locks to turn on. Eg, L_SCR | L_NUM.
off Bitwise AND of the keys to turn off. Eg, L_NUM | L_CAP.
Returns
The current state of the lock keys.
-------------------------------------------------------------------------------
Function longdate
Prototype in date.h
Module date
Library tll
datest *longdate(datest *ds,long d)
Given a Day number as per function datelong, return the date in the
variable pointed to by 'ds'.
-------------------------------------------------------------------------------
Function longdow
Prototype in date.h
Module date
Library tll
int longdow(long d)
Given a Day number as per function datelong, return the day of the week
on that day(1-7). Sunday is the 1st day of the week, Saturday is the 7th.
-------------------------------------------------------------------------------
Function monlen
Prototype in date.h
Module date
Library tll
int monlen(int m,int y)
Given month(1-12) and year(1-32767), return the length of the month.
monlen(2,1991) returns 28 (February 1991 has 28 days)
monlen(2,1992) returns 29 (February 1992 has 29 days)
-------------------------------------------------------------------------------
Function monsum
Prototype in date.h
Module date
Library tll
int monsum(int m,int y)
Given month(1-12) and year(1-32767), return the number of days within
the year prior to the first of that month (0-335).
monsum(1,1991) returns 0 (01/01/1991 is Day 1 of 1991)
monsum(2,1991) returns 31 (01/02/1991 is Day 32 of 1991)
monsum(3,1991) returns 59 (01/03/1991 is Day 60 of 1991)
monsum(3,1992) returns 60 (01/03/1992 is Day 61 of 1992 - leapyear)
-------------------------------------------------------------------------------
Function monthnam
Prototype in date.h
Module date
Library tll
char *monthnam(int m)
Returns a pointer to the 3-letter month name corresponding to the
month number parsed. Eg, 1 returns "Jan".
-------------------------------------------------------------------------------
Function monthname
Prototype in date.h
Module date
Library tll
char *monthname(int m)
Returns a pointer to the full month name corresponding to the
month number parsed. Eg, 1 returns "January".
-------------------------------------------------------------------------------
Function mplay
Prototype in music.h
Module music
Library tll
char *mplay(char *szName)
Polyphonic Music Player v1.2
Written in DeSmet C and placed in the public domain
by: Mike Talvola
Agoura Hills, CA
Permission is hereby granted to copy, modify, and
otherwise use this program except for profit.
Inspired by "Polyphonic Music on the IBM PC"
by: Steve Muenter
This function uses tri() to play a tune stored in a file. The file has a
default extension of ".POL", and should contain a series of integers
seperated by blanks or newlines. Each of the integers should be in the
format specified for tri().
Parameters
szName A pointer to the filename containing the data to play.
Returns
A pointer to the name of the file played.
-------------------------------------------------------------------------------
Function play
Prototype in music.h
Module music
Library tll
void play(char *s)
Plays notes from the character string s. S should contain a sequence of
commands, optionally followed by a single digit argument, as follows :
Command Argument Function
A-G 1-9 Play the note, set the length for this note only
if the argument is present.
T 0-9 Set the tempo from 0 (fastest) to 9 (slowest).
L 1-9 Set the default note length from 1 (full note) to
9 (1/256th note).
O 0-9 Set the octave from 0 (lowest) to 9 (highest).
@ filename Continue getting commands from the specified file.
Unless this is the last command in the string, the
argument should be terminated by another '@'. The
file can contain multiple lines, and can contain
another '@' command. '@'s can be nested until you
run out of memory.
Parameters
s A pointer to the string holding the commands to play.
Returns
Nothing
-------------------------------------------------------------------------------
Function randomise
Prototype in random.h
Module random
Library tll
void randomise(void)
This function is only here to correct a spelling mistake in Turbo-C
(if you're Aussie it's a spelling mistake anyway). I got sick of having
to correct myself.
All it does is seed the random number generator from the PC's clock.
Parameters
none
Returns
nothing
-------------------------------------------------------------------------------
Function readcmos
Prototype in cmos.h
Module cmos
Library tll
int readcmos(int port)
Read a CMOS location, waiting for a valid RTC value before returning if
the location is an RTC location.
Parameters
port The location to read, range from 0x00 to 0xff.
Returns
The value at that location, range from 0x00 to 0xff.
-------------------------------------------------------------------------------
Function setenvp
Prototype in env.h
Module env
Library tll
int setenvp(char *var,char *val)
Set a variable in the root environment. If the variable does not exist,
create it. If it does, replace it.
Parameters
var The variable to set.
val The value to give it.
Returns
TRUE if the variable could be set, FALSE if there wasn't enough room.
-------------------------------------------------------------------------------
Function settimer
Prototype in misc.h
Module misc
Library tll
void settimer(ulong hz)
Theoretically this function changes the PC's 18.2hz clock pulses to any
desired frequency, but as far as I can tell, it doesn't seem to work.
Maybe the next version.
Parameters
hz The desired clock frequency.
Returns
nothing
-------------------------------------------------------------------------------
Function trapbreak
Prototype in misc.h
Module misc
Library tll
void trapbreak(void)
This detects all the various BREAK key combinations and ignores them.
Anything else is passed through to the normal keyboard handler. The
key combinations which are ignored are as follows :
CTRL-2
CTRL-ScrlLock
CTRL-C
CTRL-ALT-Delete
ALT-Keypad0 to Keypad9
Note this last one. The user can normally use the keypad keys with <ALT>
to generate any ASCII code. If they generate ASCII 3, this is interpreted
as a BREAK. To prevent this, I disable the <ALT>keypad function completely.
This was infinitely easier than trying to interfere with the BIOS routine
which accumulates the <ALT>keypad keystrokes and delivers the ASCII value.
Also, CTRL-ALT-Delete is trapped. I figure if you don't want the user
breaking out of your program, you don't want him rebooting your machine
either. An interesting note is that we can never take away the power
switch, so if the idiot really wants to, he can always stuff up his data
one way or another. However, the purpose of this routine is simply to
make sure he doesn't do it accidentally.
This function is one of three. The other two are endtrap and traphandler.
Endtrap is called to turn BREAK key trapping off. Traphandler should not
be called by the programmer. It is the interrupt handler.
Parameters
none
Returns
nothing
-------------------------------------------------------------------------------
Function traphandler
Prototype in misc.h
Module misc
Library tll
void interrupt traphandler(void)
The interrupt handler for BREAK key checking. See trapbreak.
Should not be called by the programmer.
Parameters
none
Returns
nothing
-------------------------------------------------------------------------------
Function tri
Prototype in music.h
Module music
Library tll
void tri(short *tune)
play 3-voice music
Copyright (C) A.Bogatyrev (abs)
Moscow 1990.
Program is placed in the public domain by: ABS.
Permission is hereby granted to copy, modify,
and otherwise use this program except for profit.
.................................................
Modified by: Kevin Spencer
17 Winchelsea Rd,
NOLLAMARA WA 6061
Takes an array of 'short', and plays it. Each element in the array must
be at least 16 bits long. The highest 3 bits represent the Command, and
the lowest 13 bits represent the Value. The commands are as follows :
000 End-Of-Tune
001 Delay for Value, then play Voices 1,2 & 3
010 Change Tempo to Value
011 Ignore this Value
100 Set Pitch for Voice 1
101 Set Pitch for Voice 2
110 Set Pitch for Voice 3
111 Set Pitch for Voice 3
Note that this is only my best guess at how this thing really works.
Take it with a pinch of salt.
Parameters
tune A pointer to the array described above.
Returns
Nothing
-------------------------------------------------------------------------------
Function updateclock
Prototype in cmos.h
Module cmos
Library tll
void updateclock(void)
Update DOS' date/time using the value in the CMOS Real-Time-Clock.
Parameters
none
Returns
nothing
-------------------------------------------------------------------------------